Commands
********

This section is a semi-automatically bowdlerized version of the Vi reference created by
 maart@cs.vu.nl and others. It can be found on the Vi archives. Very little has been changed for Viper.

Groundwork
==========

The VI command set is based on the idea of combining motion commands with other commands. The motion command is used as a text region specifier for other commands. We classify motion commands into point commands and line commands.

The point commands are:

     h, l, 0,  $, w, W, b, B, e, E, (, ), /, ?, `, f, F, t, T, %, ;, ,, ^

The line commands are:

     j, k, +, -, H, M, L, {, }, G, ',  [[, ]], []

Text Deletion Commands (see Deleting Text), Change commands (see Changing Text), even Shell Commands (see Shell Commands) use these commands to describe a region of text to operate on.

Viper adds two region descriptors, r and R. These describe the Emacs regions (see Basics), but they are not movement commands.

The command description uses angle brackets <> to indicate metasyntactic variables, since the normal conventions of using simple text can be confusing with Viper where the commands themselves are characters. Watch out where < shift commands and <count> are mentioned together!!!

<move> refers to the above movement commands, and <a-z> refers to registers or textmarkers from a to z. Note that the <move>  is described by full move commands, that is to say they will take counts, and otherwise behave like normal move commands. <address> refers to Ex line addresses, which include

. <No address>
     Current line

.+n .-n
     Add or subtract for current line

number
     Actual line number, use .= to get the line number

'<a-z>
     Textmarker

$
     Last line

x,y
     Where x and y are one of the above

%
     For the whole file, same as (1,$).

/pat/

?pat?
     Next or previous line with pattern pat

Note that % is used in Ex commands to mean current file. If you want a % in your command, it must be escaped as \%. Similarly, # expands to the previous file. The previous file is the first file in :args listing. This defaults to previous window in the VI sense if you have one window only.

Others like <args> -- arguments, <cmd> -- command etc. should be fairly obvious.

Common characters referred to include:

<sp>
     Space

<ht>
     Tab

<lf>
     Linefeed

<esc>
     Escape

<cr>
     Return, Enter

We also use word for alphanumeric/non-alphanumeric words, and WORD for whitespace delimited words. char refers to any ASCII character, CHAR to non-whitespace character. Brackets [] indicate optional parameters; <count> also optional, usually defaulting to 1. Brackets are elided for <count> to eschew obfuscation.

The usual Emacs convention is used to indicate Control Characters, i.e C-h for Control-h. Do not confuse this to mean the separate characters C - h!!! The ^ is itself, never used to indicate a Control character.

Text Handling
=============

Move Commands
-------------

<count>  h  C-h
     <count> chars to the left.

<count>  j  <lf> C-n
     <count> lines downward.

<count>  l  <sp>
     <count> chars to the right.

<count>  k  C-p
     <count> lines upward.

<count>  $
     To the end of line <count> from the cursor.

<count>  ^
     To the first CHAR <count> - 1 lines lower.

<count>  -
     To the first CHAR <count> lines higher.

<count>  +  <cr>
     To the first CHAR <count> lines lower.

0
     To the first char of the line.

<count> |
     To column <count>

<count>  f<char>
     <count> <char>s to the right (find).

<count>  t<char>
     Till before <count> <char>s to the right.

<count>  F<char>
     <count> <char>s to the left.

<count>  T<char>
     Till after <count> <char>s to the left.

<count>  ;
     Repeat latest f t F T <count> times.

<count>  ,
     Repeat latest f t F T <count> times in opposite direction.

<count>  w
     <count> words forward.

<count>  W
     <count> WORDS forward.

<count>  b
     <count> words backward.

<count>  B
     <count> WORDS backward.

<count>  e
     To the end of word <count> forward.

<count>  E
     To the end of WORD <count> forward.

<count>  G
     Go to line <count> (default end-of-file).

<count>  H
     To line <count> from top of the screen (home).

<count>  L
     To line <count> from bottom of the screen (last).

M
     To the middle line of the screen.

<count>  )
     <count> sentences forward.

<count>  (
     <count> sentences backward.

<count>  }
     <count> paragraphs forward.

<count>  {
     <count> paragraphs backward.

<count>  ]]
     To the <count>th heading.

<count>  [[
     To the <count>th previous heading.

<count>  []
     To the end of <count>th heading.

m<a-z>
     Mark the cursor position with a letter.

`<a-z>
     To the mark.

'<a-z>
     To the first CHAR of the line with the mark.

[<a-z>
     Show contents of textmarker.

]<a-z>
     Show contents of register.

``
     To the cursor position before the latest absolute jump (of which are examples / and G).

''
     To the first CHAR of the line on which the cursor was placed before the latest absolute jump.

<count>  /<string>
     To the <count>th occurrence of <string>.

<count>  /<cr>
     To the <count>th occurrence of <string> from previous / or ?.

<count>  ?<string>
     To the <count>th previous occurrence of <string>.

<count>  ?<cr>
     To the <count>th previous occurrence of <string> from previous ? or /.

n
     Repeat latest / ? (next).

N
     Repeat latest search in opposite direction.

C-c /
     Without a prefix argument, this command toggles case-sensitive/case-insensitive search modes and plain vanilla/regular expression search. With the prefix argument 1, i.e., 1 C-c /, this toggles case-sensitivity; with the prefix argument 2, toggles plain vanilla search and search using regular expressions. See Viper Specials, for alternative ways to invoke this function.

%
     Find the next bracket and go to its match.

Marking
-------

Emacs mark is referred to in the region specifiers r and R. See Emacs Preliminaries and see Basics for explanation. Also see Mark (The GNU Emacs manual), for an explanation of the Emacs mark ring.

m<a-z>
     Mark the current file and position with the specified letter.

m .
     Set the Emacs mark (see Emacs Preliminaries) at point.

m <
     Set the Emacs mark at beginning of buffer.

m >
     Set the Emacs mark at end of buffer.

m ,
     Jump to the Emacs mark.

:mark <char>
     Mark position with text marker named <char>. This is an Ex command.

:k <char>
     Same as :mark.

``
     Exchange point and mark.

''
     Exchange point and mark and go to the first CHAR on line.

'<a-z>
     Go to specified Viper mark.

     Go to specified Viper mark and go to the first CHAR on line.

Appending Text
--------------

See Options to see how to change tab and shiftwidth size. See the GNU Emacs manual, or try C-ha tabs (If you have turned Emacs help on). Check out the variable indent-tabs-mode to put in just spaces. Also see options for word-wrap.

<count>  a
     <count> times after the cursor.

<count>  A
     <count> times at the end of line.

<count>  i
     <count> times before the cursor (insert).

<count>  I
     <count> times before the first CHAR of the line

<count>  o
     On a new line below the current (open). The count is only useful on a slow terminal.

<count>  O
     On a new line above the current. The count is only useful on a slow terminal.

<count>  ><move>
     Shift the lines described by <count><move> one shiftwidth to the right (layout!).

<count>  >>
     Shift <count> lines one shiftwidth to the right.

<count>  ["<a-z1-9>]p
     Put the contents of the (default undo) buffer <count> times after the cursor. The register will be automatically downcased.

<count>  ["<a-z1-9>]P
     Put the contents of the (default undo) buffer <count> times before the cursor. The register will

[<a-z>
     Show contents of textmarker.

]<a-z>
     Show contents of register.

<count>  .
     Repeat previous command <count> times. For destructive commands as well as undo.

f1 1 and f1 2
     While . repeats the last destructive command, these two macros repeat the second-last and the third-last destructive commands. See Vi Macros, for more information on Vi macros.

C-c M-p and C-c M-n
     In Vi state, these commands help peruse the history of Vi's destructive commands. Successive typing of C-c M-p causes Viper to search the history in the direction of older commands, while hitting C-c M-n does so in reverse order. Each command in the history is displayed in the Monibuffer. The displayed command can then be executed by typing `.'.

     Since typing the above sequences of keys may be tedious, the functions doing the perusing can be bound to unused keyboard keys in the ~/.vip file. See Viper Specials, for details.

Editing in Insert State
-----------------------

Minibuffer can be edited similarly to Insert state, and you can switch between Insert/Replace/Vi states at will. Some users prefer plain Emacs feel in the Minibuffer. To this end, set VIP-VI-STYLE-IN-MINIBUFFER to nil.

C-v
     Deprive the next char of its special meaning (quoting).

C-h
     One char back.

C-w
     One word back.

C-u
     Back to the begin of the change on the current line.

Deleting Text
-------------

There is one difference in text deletion that you should be aware of. This difference comes from Emacs and was adopted in Viper because we find it very useful. In Vi, if you delete a line, say, and then another line, these two deletions are separated and are put back separately if you use the p command. In Emacs (and Viper), successive series of deletions that are not interrupted by other commands are lumped together, so the deleted text gets accumulated and can be put back as one chunk. If you want to break a sequence of deletions so that the newly deleted text could be put back separately from the previously deleted text, you should perform a non-deleting action, e.g., move the cursor one character in any direction.

<count>  x
     Delete <count> chars under and after the cursor.

<count>  X
     Delete <count> chars before the cursor.

<count>  d<move>
     Delete from point to endpoint of <count><move>.

<count>  dd
     Delete <count> lines.

D
     The rest of the line.

<count>  <<move>
     Shift the lines described by <count><move> one shiftwidth to the left (layout!).

<count>  <<
     Shift <count> lines one shiftwidth to the left.

Changing Text
-------------

<count>  r<char>
     Replace <count> chars by <char> - no <esc>.

<count>  R
     Overwrite the rest of the line, appending change COUNT - 1 times.

<count>  s
     Substitute <count> chars.

<count>  S
     Change <count> lines.

<count>  c<move>
     Change from begin to endpoint of <count><move>.

<count>  cc
     Change <count> lines.

<count>  C
     The rest of the line and <count> - 1 next lines.

<count>  =<move>
     Reindent the region described by move.

<count>  ~
     Switch lower and upper cases.

<count>  J
     Join <count> lines (default 2).

:[x,y]s/<p>/<r>/<f>
     Substitute (on lines x through y) the pattern <p> (default the last pattern) with <r>.  Useful flags <f> are g for global (i.e. change every non-overlapping occurrence of <p>) and c for confirm (type y to confirm a particular substitution, else n ).  Instead of / any punctuation CHAR unequal to <space> <tab> and <lf> can be used as delimiter.

:[x,y]copy [z]
     Copy text between x and y to the position after z.

:[x,y]t [z]
     Same as :copy.

:[x,y]move [z]
     Move text between x and y to the position after z.

&
     Repeat latest Ex substitute command, e.g. :s/wrong/good.

C-c /
     Toggle case-sensitive search. With prefix argument, toggle vanilla/regular expression search.

#c<move>
     Change upper case characters in the region to lower case.

#C<move>
     Change lower case characters in the region to upper case.

#q<move>
     Insert specified string at the beginning of each line in the region

C-c M-p and C-c M-n
     In Insert and Replace states, these keys are bound to commands that peruse the history of the text previously inserted in other insert or replace commands. By repeatedly typing C-c M-p or C-c M-n, you will cause Viper to insert these previously used strings one by one. When a new string is inserted, the previous one is deleted.

     In Vi state, these keys are bound to functions that peruse the history of destructive Vi commands. See Viper Specials, for details.

Search and Replace
------------------

See Groundwork, for Ex address syntax. See Options to see how to get literal (non-regular-expression) search and how to stop search from wrapping around.

<count>  /<string>
     To the <count>th occurrence of <string>.

<count>  ?<string>
     To the <count>th previous occurrence of <string>.

<count>  g<move>
     Search for the text described by move. (off by default)

n
     Repeat latest / ? (next).

N
     Idem in opposite direction.

%
     Find the next bracket and go to its match

:[x,y]g/<string>/<cmd>
     Search globally [from line x to y] for <string> and execute the Ex <cmd> on each occurrence.

:[x,y]v/<string>/<cmd>
     Execute <cmd> on the lines that don't match.

#g<move>
     Execute the last keyboard macro for each line in the region. See Macros and Registers, for more info.

Q
     Query Replace.

:ta <name>
     Search in the tags file where <name> is defined (file, line), and go to it.

:[x,y]s/<p>/<r>/<f>
     Substitute (on lines x through y) the pattern <p> (default the last pattern) with <r>.  Useful flags <f> are g for global (i.e. change every non-overlapping occurrence of <p>) and c for confirm (type y to confirm a particular substitution, else n).  Instead of / any punctuation CHAR unequal to <space> <tab> and <lf> can be used as delimiter.

&
     Repeat latest Ex substitute command, e.g. :s/wrong/good.

Yanking
-------

<count>  y<move>
     Yank from begin to endpoint of <count><move>.

<count>  "<a-z>y<move>
     Yank from begin to endpoint of <count><move> to register.

<count>  "<A-Z>y<move>
     Yank from begin to endpoint of <count><move> and append to register.

<count>  yy
     <count> lines.

<count>  Y
     Idem (should be equivalent to y$ though).

m<a-z>
     Mark the cursor position with a letter.

[<a-z>
     Show contents of textmarker.

]<a-z>
     Show contents of register.

<count>  ["<a-z1-9>]p
     Put the contents of the (default undo) buffer <count> times after the cursor. The register will be automatically downcased.

<count>  ["<a-z1-9>]P
     Put the contents of the (default undo) buffer <count> times before the cursor. The register will

Undoing
-------

u U
     Undo the latest change.

.
     Repeat undo.

:q!
     Quit Vi without writing.

:e!
     Re-edit a messed-up file.

:rec
     Recover file from autosave. Viper also creates backup files that have a ~ appended to them.

Display
=======

C-g
     At user level 1, give file name, status, current line number and relative position.

     At user levels 2 and higher, abort the current command.

C-c g
     Give file name, status, current line number and relative position -- all user levels.

C-l
     Refresh the screen.

<count> C-e
     Expose <count> more lines at bottom, cursor stays put (if possible).

<count> C-y
     Expose <count> more lines at top, cursor stays put (if possible).

<count> C-d
     Scroll <count> lines downward (default the number of the previous scroll; initialization: half a page).

<count> C-u
     Scroll <count> lines upward (default the number of the previous scroll; initialization: half a page).

<count> C-f
     <count> pages forward.

<count> C-b
     <count> pages backward (in older versions C-b only works without count).

<count> z<cr>

zH
     Put line <count> at the top of the window (default the current line).

<count> z-

zL
     Put line <count> at the bottom of the window (default the current line).

<count> z.

zM
     Put line <count> in the center of the window (default the current line).

File and Buffer Handling
========================

In all file handling commands, space should be typed before entering the file name. If you need  to type a modifier, such as >> or !, don't put any space between the command and the modifier.

:q
     Quit buffer except if modified.

:q!
     Quit buffer without checking. In Viper, these two commands are identical. Confirmation is required if exiting modified buffers that visit files.

:susp

:stop
     Suspend Viper

:[x,y] w
     Write the file.

:[x,y] w <name>
     Write to the file <name>.

:[x,y] w>> <name>
     Append the buffer to the file <name>.  There should be no space between w and >>. Type space after the >> and see what happens.

:w! <name>
     Overwrite the file <name>. In Viper, :w and :w! are identical. Confirmation is required for writing to an existing file (if this is not the file the buffer is visiting) or to a read-only file.

:x,y w <name>
     Write lines x through y to the file <name>.

:wq
     Write the file and kill buffer.

:r <file> [<file> ...]
     Read file into a buffer, inserting its contents after the current line.

:xit
     Same as :wq.

:W
     Save unsaved buffers, asking for confirmation.

:WW
     Like W, but without asking for confirmation.

ZZ
     Save current buffer and kill it. If user level is 1, then save all files and kill Emacs. Killing Emacs is the wrong way to use it, so you should switch to  higher user levels as soon as possible.

:x [<file>]
     Save and kill buffer.

:x! [<file>]
     :w![<file>] and :q.

:pre
     Preserve the file -- autosave buffers.

:rec
     Recover file from autosave.

:f
     Print file name and lines.

:cd [<dir>]
     Set the working directory to <dir> (default home directory).

:pwd
     Print present working directory.

:e [+<cmd>] <files>
     Edit files. If no filename is given, edit the file visited by the current buffer. If buffer was modified or the file changed on disk, ask for confirmation. Unlike Vi, Viper allows :e to take multiple arguments. The first file is edited the same way as in Vi. The rest are visited in the usual Emacs way.

:e! [+<cmd>] <files>
     Re-edit file. If no filename, reedit current file. In Viper, unlike Vi, e! is identical to :e. In both cases, the user is asked to confirm if there is a danger of discarding changes to a buffer.

:q!
     Quit Vi without writing.

C-^
     Edit the alternate (normally the previous) file.

:rew
     Obsolete

:args
     List files not shown anywhere with counts for next

:n [count]  [+<cmd>] [<files>]
     Edit <count> file, or edit files. The count comes from :args.

:N [count] [+<cmd>] [<files>]
     Like :n, but the meaning of the variable EX-CYCLE-OTHER-WINDOW is reversed.

:b
     Switch to another buffer. If EX-CYCLE-OTHER-WINDOW is t, switch in another window. Buffer completion is supported.

:B
     Like :b, but the meaning of EX-CYCLE-OTHER-WINDOW is reversed.

:<address>r <name>
     Read the file <name> into the buffer after the line <address>.

v, V, C-v
     Edit a file in current or another window, or in another frame. File name is typed in Minibuffer. File completion and history are supported.

Mapping
=======

:map <string>
     Start defining a Vi-style keyboard macro. For instance, typing :map www followed by :!wc % and then typing C-x ) will cause www to run wc on current file (Vi replaces % with the current file name).

C-x )
     Finish defining a keyboard macro. In Viper, this command completes the process of defining all keyboard macros, whether they are Emacs-style or Vi-style. This is a departure from Vi, needed to allow WYSIWYG mapping of keyboard macros and to permit the use of function keys and arbitrary Emacs functions in the macros.

:unmap <string>
     Deprive <string> of its mappings in Vi state.

:map! <string>
     Map a macro for Insert state.

:unmap! <string>
     Deprive <string> of its mapping in Insert state (see :unmap).

@<a-z>
     In Vi state, execute the contents of register as a command.

@@
     In Vi state, repeat last register command.

@#
     In Vi state, begin keyboard macro. End with @<a-z>. This will put the macro in the proper register. Register will be automatically downcased. See Macros and Registers, for more info.

@!<a-z>
     In Vi state, yank anonymous macro to register

*
     In Vi state, execute anonymous macro (defined by C-x( and C-x )).

C-x e
     Like *, but works in all Viper states.

#g<move>
     Execute the last keyboard macro for each line in the region. See Macros and Registers, for more info.

[<a-z>
     Show contents of textmarker.

]<a-z>
     Show contents of register.

Shell Commands
==============

Note that % is used in Ex commands to mean current file. If you want a % in your command, it must be escaped as \%. However if % is the first character, it stands as the address for the whole file. Similarly, # expands to the previous file. The previous file is the first file in :args listing. This defaults to the previous file in the VI sense if you have one window.

:sh
     Execute a subshell in another window

:[x,y]!<cmd>
     Execute a shell <cmd> [on lines x through y; % is replace by current file, \% is changed to %

:[x,y]!! [<args>]
     Repeat last shell command [and append <args>].

:!<cmd>
     Just execute command and display result in a buffer.

:!! <args>
     Repeat last shell command and append <args>

<count> !<move><cmd>
     The shell executes <cmd>, with standard input the lines described by <count><move>, next the standard output replaces those lines (think of cb, sort, nroff, etc.).

<count> !!<cmd>
     Give <count> lines as standard input to the shell <cmd>, next let the standard output replace those lines.

:[x,y] w !<cmd>
     Let lines x to y be standard input for <cmd> (notice the <sp> between w and !).

:<address>r !<cmd>
     Put the output of <cmd> after the line <address> (default current).

:<address>r <name>
     Read the file <name> into the buffer after the line <address> (default current).

Options
=======

ai
     autoindent -- In append mode after a <cr> the cursor will move directly below the first CHAR on the previous line.

ic
     ignorecase -- No distinction between upper and lower cases when searching.

magic
     Regular expressions used in searches; nomagic means no regexps.

ro
     readonly -- The file is not to be changed. If the user attempts to write to this file, confirmation will be requested.

sh=<string>
     shell -- The program to be used for shell escapes (default $SHELL (default /bin/sh)).

sw=<count>
     shiftwidth -- Gives the shiftwidth (default 8 positions).

sm
     showmatch -- Whenever you append a ), Vi shows its match if it's on the same page; also with { and }.  If there's no match, Vi will beep.

ts=<count>
     tabstop -- The length of a <ht>; warning: this is only IN the editor, outside of it <ht>s have their normal length (default 8 positions).

wm=<count>
     wrapmargin -- In append mode Vi automatically puts a <lf> whenever there is a <sp> or <ht> within <wm> columns from the right margin.

ws
     wrapscan -- When searching, the end is considered stuck to the begin of the file.

:set <option>
     Turn <option> on.

:set no<option>
     Turn <option> off.

:set <option>=<value>
     Set <option> to <value>.

Emacs Related Commands
======================

_
     Begin Meta command in Vi state. Most often used as _x (M-x).

C-z
     Begin Meta command in Insert state.

C-z
     Switch between Emacs and Vi states.

C-x0
     Close Window

C-x1
     Close Other Windows

C-x2
     Split Window

C-xo
     Move among windows

C-xC-f
     Emacs find-file, useful in Insert state

C-y
     Put back the last killed text. Similar to Vi's p, but also works in Insert and Replace state. This command doesn't work in Vi command state, since this binding is taken for something else.

M-y
     Undoes the last C-y and puts another kill from the kill ring. Using this command, you can try may different kills until you find the one you need.

Mouse-bound Commands
====================

The following two mouse actions are normally bound to to special search and insert commands in of Viper:

S-mouse-1 (Emacs)

meta button1up (XEmacs)
     Holding Shift (or Meta, if XEmacs) and clicking mouse button 1 will initiate search for a region under the mouse pointer. This command can take a prefix argument. Note: Viper sets this binding only if this mouse action is not already bound to something else. See Viper Specials, for more information.

S-mouse-2 (Emacs)

meta button2up (XEmacs)
     Holding Shift (or Meta, if XEmacs) and clicking button 2 of the mouse will insert a region surrounding the mouse pointer. This command can also take a prefix argument. Note: Viper sets this binding only if this mouse action is not already bound to something else. See Viper Specials, for more details.